home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / lists / gem / l_0799 / 667 < prev    next >
Internet Message Format  |  1994-08-27  |  11KB
  1. Date: Sat, 2 Jul 94 00:29 CDT
  2. From: ekl@sdf.lonestar.org (Evan K. Langlois)
  3. To: gem-list@world.std.com
  4. Subject: Dialogs & Extra Buttons
  5. Precedence: bulk
  6.  
  7.   The following is for dialog boxes, since these came up.  Dialogs should
  8. use the exact same hot-keys and editing keys that the application uses.
  9. This set of rules is largely from the ATARI Compendium and ATARI developer
  10. guidelines.  You should get these and read them.  Just because it works on
  11. your system, doesn't mean it is correct.  Failure to follow all programming
  12. guidelines can result in "quirks", hardware dependance, messy window redraw,
  13. or dead-locked applications (ex.  Don't call wind_update (BEG_UPDATE) before
  14. evnt_multi)!  A complete list of all guidelines is beyond the scope of the
  15. GEM-List.  The GEM-List only supplements ATARI's documentation.
  16.  
  17.   If you have AES 3.4 or greater, you should check and see what features
  18. are present in the system using appl_getinfo().
  19.  
  20.  
  21. Guidelines for Dialog Boxes :
  22. =============================
  23.  
  24.   Use these guidelines for all Dialog Boxes -
  25.  
  26.   o  Prior to drawing a dialog and calling form_do(), call wind_update
  27. (BEG_UPDATE).  Do not call wind_update (END_UPDATE) until the dialog is
  28. removed and user-interaction is complete.
  29.  
  30.   o  If a dialog box controls a physical attribute (fill style, text font,
  31. etc), then the dialog box should contain a sample area, where changes are
  32. shown before the user exits the dialog functions.
  33.  
  34.   o  Dialogs that position themselves over the mouse cursor, or in the
  35. center of the active window should allow this feature to be disabled as it
  36. annoys some users.
  37.  
  38.   o  Dialogs boxes should present buttons in order (left-to-right or top-down)
  39. of "Ok", "Cancel", .. other buttons .., "Help".  
  40.  
  41.   o  Unfolding dialogs should use the symbol ">>" on a button to show which
  42. button unfolds the dialog (for "advanced" users) and the "<<" symbol should
  43. return the dialog to its original form.  ex : "More >>" changes to "<< Less"
  44. when the dialog expands; "Options >>" changes to "<< Options"
  45.  
  46.   o  If you directly modify a dialog with VDI calls, make you you call
  47. objc_offset first, since the user may have moved the dialog.  If you have
  48. an active-scrollbar, use objc_offset once when you detect the mouse down
  49. and update your display when needed using VDI bit-blit functions until
  50. the mouse is released.  A double-click on the slider "knob" should display
  51. an alert to let the user choose between active and passive scrollers when
  52. you wish to allow an active scroller.
  53.  
  54.  
  55. Over-riding FORM_DO :
  56. ---------------------
  57.  
  58.   Use these guidelines to construct your own form_do().  It should emulate
  59. form_do() EXACTLY!  I recommend that you use form_do() and not write
  60. your own handler for the majority of user interaction, allowing a custom
  61. global form_do() replacement to be used to keep interfaces consistent.
  62.  
  63.   This may include the following.
  64.  
  65.   o  if the dialog will be completely modal, call wind_update (BEG_MCTRL)
  66. after wind_update (BEG_UPDATE).  When the dialog is complete, call wind_update
  67. (END_MCTRL) and wind_update (END_UPDATE).
  68.  
  69.   o  Find the mouse cursor using events, do not poll the mouse location.  To
  70. provide "hot"-objects use mouse "rectangle" events.
  71.  
  72.   o  If you put your dialog in a window, the "closer" should be the same as
  73. CANCEL or ABORT.  The "mover" should allow moving the dialog.  If you want
  74. the dialog to be partially modal, then top the dialog window instead of other
  75. windows when you recieve a window top message and disable your menu bar.  In
  76. either case, you main evnt_multi() code should handle dialog interaction with
  77. objc_edit and objc_find and related calls.  Either be sure your window is
  78. topped (only 1 rectangle - check while in wind_update) or walk rectangles.
  79. Obviously, user interaction should not be handled while in any sort of wind_
  80. update as window dialogs are windows that have objc_draw as a redraw.
  81.  
  82.   o  Fully non-modal dialogs are difficult on both the programmer and the
  83. user.  Some possibilities would be a font-selection dialog, where the user
  84. could change fonts with the dialog and edit the document at the same time.
  85. In these cases, OK doesn't have to end the dialog, just make the proper change
  86. in the document, and the closer removes the dialog.
  87.  
  88.   o  The new TOOLBAR settings may make dialog handling a bit easier.  It
  89. handles the redraw (usually) and send you messages when the user clicks a
  90. button.
  91.  
  92.  
  93. Alert Boxes :
  94. -------------
  95.  
  96.   Alerts should follow all the rules of dialog boxes, plus these additional
  97. guidelines and suggestions.
  98.  
  99.   o  Whenever possible provide the user with more than one exit button
  100.  
  101.   o  Never provide both an OK button and a CANCEL button when both will
  102. lead to the same action/inaction.
  103.  
  104.   o  Avoid using the word "error" or any term which may blame the user.
  105.  
  106.   o  If an error has occured, suggest a remedy.
  107.  
  108.   o  Use 'Cannot' instead of "Can not' or 'Can't"
  109.  
  110.   o  If an alert might occur while another application has focus, then
  111. the first line of the alert text should be the program name, followed by
  112. a colon ':'
  113.  
  114.   o  A message such as 'Not enough memory to load file TEST.DOC' is more
  115. informative than 'Insufficient memory'.  
  116.  
  117.   o  Minor warnings may be increasingly apparent, by ringing the system bell
  118. at the first occurance and displaying a dialog box to guide the user on the
  119. next occurance.
  120.  
  121.   o  Message Text should be left aligned.
  122.  
  123.   o  If a message cannot fit into 5 lines x 30 characters, either downsize
  124. the alert for clarity, or place it in a longer form.  Do NOT use consecutive
  125. alerts.
  126.  
  127.   o  Alerts should be capatalized by standard grammatical rules, and should 
  128. end in a question mark or period, never an exclamation point.
  129.  
  130.   Icons are to be used as follows :
  131.  
  132.   0  For credits, reminders and help
  133.   1  Error Conditions or conditions requiring immediate attension
  134.   2  Inquiries and most confirmations
  135.   3  Potentially Program Fatal errors, confirmation of an irreversible action
  136.   4  Informational Alert, with just an OK (if you don't have it, use 0)
  137.   5  General Disk Errors and Requests (if you don't have it, use 1)
  138.  
  139.  
  140. Since, I'm on a roll .. lemme cover mouse forms and the right mouse button
  141.  
  142.  
  143. MOUSE FORMS
  144. ===========
  145.  
  146.   Change to the appropriate mouse form whenever you get the following
  147. messages :  WM_TOPPED or WM_ONTOP.
  148.  
  149.   Mouse forms and my suggestions:
  150.  
  151.   0    ARROW        General Purpose Shape
  152.   1    TEXT_CRSR    Application expects text entry into this object
  153.   2    BUSY_BEE     Application is doing heavy calculations/disk access
  154.   3    POINT_HAND   You are resizing the object
  155.   4    FLAT_HAND    You are grabbing/moving the object
  156.   5    THIN_CROSS   For "setting" points, such as a CAD or DTP application
  157.   6    THICK_CROSS  For selecting from a large menu, like a dialing directory
  158.   7    OUTLN_CROSS  For selecting blocks of text or spreadsheet cells.
  159.   255  USER_DEF     For paint program brushes, special program "modes", such
  160.                     as a help mode, etc.
  161.   256  M_OFF        Remove mouse from screen (for updates).
  162.   257  M_ON         Display the mouse cursor (reverse of above).
  163.   258  M_SAVE       Saves current mouse form
  164.   259  M_RESTORE    Restore saved mouse form  (*)
  165.   260  M_LAST       Restore last mouse form   (*)
  166.  
  167. (*) These 2 entries were reversed in the ATARI Compendium, so that
  168. M_RESTORE was 260, and M_LAST was 259.  I have kept the original descriptions
  169. with the numbers, hoping these are correct.  The Compendium is obviously
  170. mixed up, but I'm only guessing on the correct formats.
  171.  
  172.  
  173. MULTIPLE BUTTONS
  174. ================
  175.  
  176.   The right mouse button should be used as follows when clicked on :
  177.  
  178.   o  An icon, or similar object :  Display a pop-up menu to let the user
  179.   open, delete, hide, or show_info about the object.  The actual menu
  180.   items are NOT significant, the fact that it calls a menu of actions
  181.   for the object IS.  This can be a VERY helpful feature in object oriented
  182.   applications (ever use Myriad Desktop?)
  183.  
  184.   o  Open Desktop :  Construct a pop-up menu identicle to the GEM menu-bar
  185.   only vertical instead of horizontal and the top line should contain the
  186.   application name (like the desk menu). Attach the GEM menus as cascading
  187.   menus to this one, using the right arrow as norma